AI observability

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
GET
POST
GET
PATCH
POST
POST
GET
GET
POST
GET
PATCH
POST
POST
GET
GET
POST
GET
POST
POST
Next page →

List all llm analytics personal spend

Return a structured personal LLM spend analysis for the requesting user. Pass date_from / date_to (absolute like 2026-04-23 or relative like -7d) to bound the window — defaults to the last 30 days, max 90 days. The product=<ai_product> query param is required and scopes the tool / model / day / trace breakdowns to a single product; supported values: posthog_code. by_product is always returned for cross-product visibility. by_day returns a day-ascending spend series for the scoped product. Pass bucket_minutes (5, 15, 30, or 60; the window may span at most 600 buckets) to additionally get by_bucket, a time-ascending series with per-bucket cost split into uncached input / output / cache read / cache creation components. Use refresh=true to bypass the 5-minute response cache.

Required API key scopes

user:read

Query parameters

  • bucket_minutes
    integer
    One of: "5""15""30""60"
  • date_from
    string
    Default: -30d
  • date_to
    string | null
  • limit
    integer
    Default: 50
  • product
    string
  • refresh
    boolean
    Default: false

Example request

GET /api/llm_analytics/@me/spend
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/llm_analytics/@me/spend/

Example response

Status 200
RESPONSE
{
  "summary": {
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "product": "string",
    "total_cost_usd": 0.1,
    "event_count": 0,
    "scoped_cost_usd": 0.1,
    "scoped_event_count": 0
  },
  "by_product": {
    "items": [
      {
        "product": "string",
        "event_count": 0,
        "cost_usd": 0.1
      }
    ],
    "truncated": true
  },
  "by_tool": {
    "items": [
      {
        "tool": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "share_of_scoped": 0.1,
        "avg_input_tokens": 0.1
      }
    ],
    "truncated": true
  },
  "by_model": {
    "items": [
      {
        "model": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "input_tokens": 0,
        "output_tokens": 0
      }
    ],
    "truncated": true
  },
  "by_day": {
    "items": [
      {
        "day": "2019-08-24",
        "event_count": 0,
        "cost_usd": 0.1,
        "input_tokens": 0,
        "output_tokens": 0
      }
    ],
    "truncated": true
  },
  "by_day_model": [
    {
      "day": "2019-08-24",
      "model": "string",
      "cost_usd": 0.1,
      "input_tokens": 0,
      "output_tokens": 0,
      "generation_count": 0
    }
  ],
  "by_bucket": {
    "items": [
      {
        "bucket_start": "2019-08-24T14:15:22Z",
        "event_count": 0,
        "cost_usd": 0.1,
        "input_cost_usd": 0.1,
        "output_cost_usd": 0.1,
        "cache_read_cost_usd": 0.1,
        "cache_creation_cost_usd": 0.1,
        "input_tokens": 0,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ],
    "bucket_minutes": 0,
    "truncated": true
  },
  "top_traces": {
    "items": [
      {
        "trace_id": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "started_at": "2019-08-24T14:15:22Z"
      }
    ],
    "truncated": true
  }
}
Status 400
RESPONSE
{
  "detail": "string"
}
Status 401
RESPONSE
{
  "detail": "string"
}
Status 403
RESPONSE
{
  "detail": "string"
}
Status 404
RESPONSE
{
  "detail": "string"
}
Status 429
RESPONSE
{
  "detail": "string"
}

List all dataset items

List a dataset's current items or its exact contents at a prior revision.

Required API key scopes

dataset:read

Query parameters

  • archived
    boolean
    Default: false
  • dataset
    string
  • limit
    integer
  • offset
    integer
  • revision
    integer

Response


Example request

GET /api/projects/:project_id/dataset_items
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
      "client_item_id": "string",
      "version": 0,
      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
      "dataset_revision": 0,
      "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
      "archived": true,
      "input": {},
      "expected_output": {},
      "source_output": {},
      "metadata": {},
      "source_trace_id": "string",
      "source_event_id": "string",
      "source_timestamp": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "version_created_at": "2019-08-24T14:15:22Z",
      "version_created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "team_id": 0
    }
  ]
}

Create dataset items

Create an item and its first immutable version. An identical client item ID retry returns the existing item. A different payload or an archived match returns a conflict.

Required API key scopes

dataset:write

Request parameters

  • dataset
    string
  • client_item_id
    string | null
  • input
  • expected_output
  • source_output
  • metadata
    object
  • source_trace_id
    string | null
  • source_event_id
    string | null
  • source_timestamp
    string | null

Response


Example request

POST /api/projects/:project_id/dataset_items
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/\
	-d dataset="string",\
	-d input=undefined

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}
Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Retrieve dataset items

Retrieve the current item version or the version visible at an exact dataset revision.

Required API key scopes

dataset:read

Path parameters

  • dataset_item_id
    string

Query parameters

  • revision
    integer

Response


Example request

GET /api/projects/:project_id/dataset_items/:dataset_item_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/:dataset_item_id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}

Update dataset items

Create a new immutable item version from editable fields.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Response


Example request

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Create dataset items

Archive an active item by creating a new immutable version.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Request parameters

  • base_version
    integer

Response


Example request

POST /api/projects/:project_id/dataset_items/:dataset_item_id/archive
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/:dataset_item_id/archive/\
	-d base_version="integer"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Create dataset items

Restore an archived item by copying content into a new immutable version.

Required API key scopes

dataset:write

Path parameters

  • dataset_item_id
    string

Request parameters

  • base_version
    integer
  • source_version
    integer | null

Response


Example request

POST /api/projects/:project_id/dataset_items/:dataset_item_id/restore
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/:dataset_item_id/restore/\
	-d base_version="integer"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
  "client_item_id": "string",
  "version": 0,
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "dataset_revision": 0,
  "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
  "archived": true,
  "input": {},
  "expected_output": {},
  "source_output": {},
  "metadata": {},
  "source_trace_id": "string",
  "source_event_id": "string",
  "source_timestamp": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "version_created_at": "2019-08-24T14:15:22Z",
  "version_created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

List all dataset items versions

List every immutable version of an item, newest first.

Required API key scopes

dataset:read

Path parameters

  • dataset_item_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/dataset_items/:dataset_item_id/versions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/dataset_items/:dataset_item_id/versions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "dataset": "d93f2be0-02b1-4d87-8b6e-fc5cba21ed8d",
      "client_item_id": "string",
      "version": 0,
      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
      "dataset_revision": 0,
      "dataset_revision_id": "e7047d72-9b1c-4feb-9c11-cc3d637eeab5",
      "archived": true,
      "input": {},
      "expected_output": {},
      "source_output": {},
      "metadata": {},
      "source_trace_id": "string",
      "source_event_id": "string",
      "source_timestamp": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "version_created_at": "2019-08-24T14:15:22Z",
      "version_created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "team_id": 0
    }
  ]
}

List all datasets

List active datasets by default, or archived datasets when requested.

Required API key scopes

dataset:read

Query parameters

  • archived
    boolean
    Default: false
  • id__in
    array
  • limit
    integer
  • offset
    integer
  • order_by
    string
    Default: -created_at
    One of: "created_at""-created_at""updated_at""-updated_at"
  • search
    string
  • tag_match
    string
    Default: any
    One of: "any""all"
  • tags
    string

Response


Example request

GET /api/projects/:project_id/datasets
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "metadata": {},
      "tags": [
        "string"
      ],
      "archived": true,
      "current_revision": 0,
      "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "team_id": 0,
      "user_access_level": "string"
    }
  ]
}

Create datasets

Create an empty dataset. Its first revision is created with its first item.

Required API key scopes

dataset:write

Request parameters

  • tags
    array
  • name
    string
  • description
    string
    Default:
  • metadata
    object

Response


Example request

POST /api/projects/:project_id/datasets
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0,
  "user_access_level": "string"
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Retrieve datasets

Retrieve an active or archived dataset.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/datasets/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0,
  "user_access_level": "string"
}

Update datasets

Update descriptive dataset fields without changing its revision.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Request parameters

  • tags
    array
  • name
    string
  • description
    string
  • metadata
    object

Response


Example request

PATCH /api/projects/:project_id/datasets/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/\
	-d tags="array"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0,
  "user_access_level": "string"
}
Status 409
RESPONSE
{
  "code": "dataset_archived",
  "detail": "string",
  "current_version": 0,
  "current_item_id": "23232ebb-d0ad-4cc6-9904-f69de444e672",
  "resource": "datasets",
  "current_count": 0,
  "limit": 0
}

Create datasets

Archive a dataset. Archived datasets remain readable and reject item mutations.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/datasets/:id/archive
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/archive/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0,
  "user_access_level": "string"
}

Create datasets exports

Create an asynchronous JSONL export pinned to an immutable dataset revision.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Request parameters

  • revision
    integer

Response


Example request

POST /api/projects/:project_id/datasets/:id/exports
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/exports/\
	-d revision="integer"

Example response

Status 201
RESPONSE
{
  "id": 0,
  "status": "pending",
  "dataset_revision": 0,
  "filename": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_after": "2019-08-24T14:15:22Z",
  "exception": "string"
}
Status 409
RESPONSE
{
  "detail": "string"
}

Retrieve datasets exports

Check the status of a dataset export created by the current user.

Required API key scopes

dataset:read

Path parameters

  • export_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/datasets/:id/exports/:export_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/exports/:export_id/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "status": "pending",
  "dataset_revision": 0,
  "filename": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_after": "2019-08-24T14:15:22Z",
  "exception": "string"
}

Retrieve datasets exports content

Download a completed dataset JSONL export.

Required API key scopes

dataset:read

Path parameters

  • export_id
    string
  • id
    string

Example request

GET /api/projects/:project_id/datasets/:id/exports/:export_id/content
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/exports/:export_id/content/

Example response

Status 200
Status 409
RESPONSE
{
  "detail": "string"
}

Create datasets

Restore an archived dataset without changing its item states.

Required API key scopes

dataset:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/datasets/:id/restore
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/restore/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "metadata": {},
  "tags": [
    "string"
  ],
  "archived": true,
  "current_revision": 0,
  "current_revision_id": "e5714292-57d7-4936-a019-416c89b9b32b",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "team_id": 0,
  "user_access_level": "string"
}

List all datasets revisions

List immutable dataset revisions, newest first.

Required API key scopes

dataset:read

Path parameters

  • id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/datasets/:id/revisions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/datasets/:id/revisions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
      "revision": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "team_id": 0
    }
  ]
}

Create llm analytics summarization

Generate an AI-powered summary of an LLM trace or event.

This endpoint analyzes the provided trace/event, generates a line-numbered text representation, and uses an LLM to create a concise summary with line references.

Two ways to use this endpoint:

  1. By ID (recommended): Pass trace_id or generation_id with an optional date_from/date_to. The backend fetches the data automatically. summarize_type is inferred.
  2. By data: Pass the full trace/event data blob in data with summarize_type. This is how the frontend uses it.

Summary Format:

  • Title (concise, max 10 words)
  • Mermaid flow diagram showing the main flow
  • 3-10 summary bullets with line references
  • "Interesting Notes" section for failures, successes, or unusual patterns
  • Line references in [L45] or [L45-52] format pointing to relevant sections

The response includes the structured summary, the text representation, and metadata.

Required API key scopes

llm_analytics:write

Request parameters

  • summarize_type
  • mode
    Default: minimal
  • data
  • force_refresh
    boolean
    Default: false
  • compact_context
    boolean
    Default: false
  • model
    string | null
  • trace_id
    string
  • generation_id
    string
  • date_from
    string | null
  • date_to
    string | null

Response


Example request

POST /api/projects/:project_id/llm_analytics/summarization
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/summarization/\
	-d summarize_type=undefined

Example response

Status 200
RESPONSE
{
  "summary": {
    "title": "User greets the assistant",
    "flow_diagram": "User → Assistant → Response",
    "summary_bullets": [
      {
        "text": "User initiated conversation with a greeting",
        "line_refs": "L5"
      },
      {
        "text": "Assistant responded with a friendly message",
        "line_refs": "L12"
      }
    ],
    "interesting_notes": [
      {
        "text": "Standard greeting pattern with no errors",
        "line_refs": ""
      }
    ]
  },
  "text_repr": "L001: user: hi\nL012: assistant: hello",
  "metadata": {
    "text_repr_length": 450,
    "model": "gpt-4.1"
  }
}
Status 400
Status 403
Status 500

Create llm analytics summarization batch check

Check which traces have cached summaries available.

This endpoint allows batch checking of multiple trace IDs to see which ones have cached summaries. Returns only the traces that have cached summaries with their titles.

Use Cases:

  • Load cached summaries on session view load
  • Avoid unnecessary LLM calls for already-summarized traces
  • Display summary previews without generating new summaries

Required API key scopes

llm_analytics:read

Request parameters

  • trace_ids
    array
  • mode
    Default: minimal
  • model
    string | null

Response


Example request

POST /api/projects/:project_id/llm_analytics/summarization/batch_check
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/summarization/batch_check/\
	-d trace_ids="array"

Example response

Status 200
RESPONSE
{
  "summaries": [
    {
      "trace_id": "string",
      "title": "string",
      "cached": true
    }
  ]
}
Status 400
Status 403
Next page →